#pragma once
// Array.h
// 作者：MetaQuotes Ltd.（整理）
// 说明：动态数组基类 CArray 接口声明，带详细中文注释

#include <Object.mqh>

/**
 * @brief 动态数组基类
 * 
 * 功能：
 *  - 提供动态数组的基本操作（增删、访问、排序等）
 *  - 支持数组与文件的保存与加载
 *  - 提供最小值、最大值搜索模板函数
 * 
 * 继承自：
 *  - CObject
 */
class CArray : public CObject
{
protected:
    int m_step_resize;  ///< 数组扩展步长
    int m_data_total;   ///< 当前元素数量
    int m_data_max;     ///< 当前数组容量（无需重新分配内存时的最大容量）
    int m_sort_mode;    ///< 数组排序模式

public:
    /**
     * @brief 构造函数，初始化数组基类
     */
    CArray(void);

    /**
     * @brief 析构函数，释放数组相关资源
     */
    ~CArray(void);

    //--- 访问受保护数据的方法

    /**
     * @brief 获取数组扩展步长
     * @return 当前数组扩展步长
     */
    int Step(void) const { return m_step_resize; }

    /**
     * @brief 设置数组扩展步长
     * @param step 新的扩展步长（必须 > 0）
     * @return 设置成功返回 true，失败返回 false
     */
    bool Step(const int step);

    /**
     * @brief 获取数组当前元素数量
     * @return 数组元素总数
     */
    int Total(void) const { return m_data_total; }

    /**
     * @brief 获取数组可用空间
     * @return 可用元素数量（m_data_max - m_data_total）
     */
    int Available(void) const { return m_data_max - m_data_total; }

    /**
     * @brief 获取数组最大容量
     * @return 数组最大容量
     */
    int Max(void) const { return m_data_max; }

    /**
     * @brief 判断数组是否按指定模式排序
     * @param mode 排序模式
     * @return 已排序返回 true，否则返回 false
     */
    bool IsSorted(const int mode=0) const { return m_sort_mode == mode; }

    /**
     * @brief 获取当前数组排序模式
     * @return 当前排序模式
     */
    int SortMode(void) const { return m_sort_mode; }

    /**
     * @brief 清空数组
     */
    void Clear(void) { m_data_total = 0; }

    //--- 与文件相关的方法

    /**
     * @brief 将数组头信息写入文件
     * @param file_handle 文件句柄
     * @return 写入成功返回 true，否则返回 false
     */
    virtual bool Save(const int file_handle);

    /**
     * @brief 从文件读取数组头信息
     * @param file_handle 文件句柄
     * @return 读取成功返回 true，否则返回 false
     */
    virtual bool Load(const int file_handle);

    //--- 排序相关方法

    /**
     * @brief 对数组进行排序
     * @param mode 排序模式（默认为 0）
     */
    void Sort(const int mode=0);

protected:
    /**
     * @brief 快速排序方法（可被派生类重写）
     * @param beg 起始索引
     * @param end 结束索引
     * @param mode 排序模式
     */
    virtual void QuickSort(int beg, int end, const int mode=0) { m_sort_mode=-1; }

    //--- 模板方法：查找最小值和最大值

    /**
     * @brief 查找数组最小值索引
     * @tparam T 数组元素类型
     * @param data 数组引用
     * @param start 起始索引
     * @param count 查找元素数量
     * @return 最小值索引，出错返回 -1
     */
    template<typename T>
    int Minimum(const T &data[], const int start, const int count) const;

    /**
     * @brief 查找数组最大值索引
     * @tparam T 数组元素类型
     * @param data 数组引用
     * @param start 起始索引
     * @param count 查找元素数量
     * @return 最大值索引，出错返回 -1
     */
    template<typename T>
    int Maximum(const T &data[], const int start, const int count) const;
};
